package com.zenithmind.coding.mapper;

import com.zenithmind.coding.pojo.entity.Problem;
import org.apache.ibatis.annotations.Mapper;
import org.apache.ibatis.annotations.Param;

import java.util.List;

/**
 * 问题推荐Mapper接口 - 遵循接口隔离原则，专门处理问题推荐相关的数据访问
 * 
 * @author ZenithMind Team
 * @since 2025-01-09
 */
@Mapper
public interface ProblemRecommendationMapper {

    /**
     * 查询推荐问题
     * 
     * @param userId 用户ID
     * @param difficulty 难度等级
     * @param limit 限制数量
     * @return 问题列表
     */
    List<Problem> selectRecommendProblems(@Param("userId") String userId,
                                         @Param("difficulty") Integer difficulty,
                                         @Param("limit") Integer limit);

    /**
     * 查询热门问题
     * 
     * @param limit 限制数量
     * @return 问题列表
     */
    List<Problem> selectHotProblems(@Param("limit") Integer limit);

    /**
     * 查询相关问题
     * 
     * @param problemId 问题ID
     * @param limit 限制数量
     * @return 问题列表
     */
    List<Problem> selectRelatedProblems(@Param("problemId") String problemId,
                                       @Param("limit") Integer limit);

    /**
     * 根据标签查询问题
     * 
     * @param tags 标签列表
     * @param limit 限制数量
     * @return 问题列表
     */
    List<Problem> selectProblemsByTags(@Param("tags") List<String> tags,
                                      @Param("limit") Integer limit);

    /**
     * 搜索问题
     * 
     * @param keyword 关键词
     * @param limit 限制数量
     * @return 问题列表
     */
    List<Problem> searchProblems(@Param("keyword") String keyword,
                                @Param("limit") Integer limit);

    /**
     * 获取每日挑战问题
     * 
     * @param userId 用户ID
     * @param date 日期
     * @param count 数量
     * @return 问题列表
     */
    List<Problem> selectDailyChallenges(@Param("userId") String userId,
                                       @Param("date") String date,
                                       @Param("count") Integer count);

    /**
     * 获取个性化学习路径
     * 
     * @param userId 用户ID
     * @param pathLength 路径长度
     * @return 问题列表
     */
    List<Problem> selectLearningPath(@Param("userId") String userId,
                                    @Param("pathLength") Integer pathLength);

    /**
     * 获取弱项强化问题
     * 
     * @param userId 用户ID
     * @param limit 限制数量
     * @return 问题列表
     */
    List<Problem> selectWeaknessReinforcementProblems(@Param("userId") String userId,
                                                     @Param("limit") Integer limit);

    /**
     * 获取同级别推荐
     * 
     * @param userId 用户ID
     * @param limit 限制数量
     * @return 问题列表
     */
    List<Problem> selectLevelMatchedProblems(@Param("userId") String userId,
                                            @Param("limit") Integer limit);

    /**
     * 获取进阶挑战
     * 
     * @param userId 用户ID
     * @param limit 限制数量
     * @return 问题列表
     */
    List<Problem> selectAdvancedChallenges(@Param("userId") String userId,
                                          @Param("limit") Integer limit);

    /**
     * 根据用户历史记录推荐问题
     * 
     * @param userId 用户ID
     * @param limit 限制数量
     * @return 问题列表
     */
    List<Problem> selectRecommendByHistory(@Param("userId") String userId,
                                          @Param("limit") Integer limit);

    /**
     * 根据协同过滤推荐问题
     * 
     * @param userId 用户ID
     * @param limit 限制数量
     * @return 问题列表
     */
    List<Problem> selectRecommendByCollaborativeFiltering(@Param("userId") String userId,
                                                          @Param("limit") Integer limit);

    /**
     * 获取趋势问题
     * 
     * @param days 天数
     * @param limit 限制数量
     * @return 问题列表
     */
    List<Problem> selectTrendingProblems(@Param("days") Integer days,
                                        @Param("limit") Integer limit);
}
